Skip to content

Support Inertia v3 protocol metadata#199

Merged
DominusKelvin merged 6 commits into
mainfrom
feat/192-support-stable-inertia-js-v3-in-inertia-sails-and-templates
May 26, 2026
Merged

Support Inertia v3 protocol metadata#199
DominusKelvin merged 6 commits into
mainfrom
feat/192-support-stable-inertia-js-v3-in-inertia-sails-and-templates

Conversation

@DominusKelvin

@DominusKelvin DominusKelvin commented May 20, 2026

Copy link
Copy Markdown
Member

Summary

Closes #192

This completes the stable Inertia v3 support lane for inertia-sails and the Boring Stack templates, including the follow-up protocol metadata work for preserved fragments and rescuable deferred props.

Companion docs: sailscastshq/docs.sailscasts.com#71

What Changed

  • Updated template root views to use the Inertia v3 JSON script boot payload.
  • Added asset-version mismatch handling for GET Inertia requests using 409 Conflict and X-Inertia-Location.
  • Changed Inertia JSON responses to use Vary: X-Inertia.
  • Omitted false clearHistory, encryptHistory, and preserveFragment flags from page objects.
  • Added sharedProps metadata.
  • Added sails.inertia.preserveFragment() and session-backed consumption across redirects.
  • Added deferred prop rescue support via .rescue() / { rescue: true } and rescuedProps metadata.
  • Omitted merge/scroll metadata for rescued props so the client never receives merge hints for missing data.
  • Added v3 merge metadata support: mergeProps, prependProps, deepMergeProps, and matchPropsOn.
  • Added nested append/prepend merge targets and item matching.
  • Added InfiniteScroll merge intent support with X-Inertia-Infinite-Scroll-Merge-Intent.
  • Strengthened JSDoc types across inertia-sails, removed a // @ts-nocheck, and added a CI-enforced check:js gate.
  • Added focused Node test coverage for page objects, render behavior, merge props, scroll props, preserve fragments, and rescued deferred props.
  • Refreshed all template lockfiles against the published inertia-sails@1.4.0 npm tarball.

Validation

  • npm view inertia-sails@1.4.0 version dist.tarball dist.integrity gitHead
  • Verified all template lockfiles resolve inertia-sails@1.4.0 to the published npm integrity.
  • npm --workspace inertia-sails run check:js
  • npm --workspace inertia-sails test
  • npx prettier --config ./.prettierrc.js --check packages/inertia-sails/index.js packages/inertia-sails/test.js packages/inertia-sails/lib/**/*.js packages/inertia-sails/tests/**/*.js
  • npx prettier --config ./.prettierrc.js --check templates/ascent-react/package-lock.json templates/ascent-vue/package-lock.json templates/mellow-react/package-lock.json templates/mellow-svelte/package-lock.json templates/mellow-vue/package-lock.json
  • git diff --check

Notes

The root jsconfig.json already enables checkJs for editor feedback. This PR adds the repeatable package-level command and GitHub Actions workflow so the same feedback is enforced outside VS Code too.

inertia-sails@1.4.0 is now published to npm, and the template lockfiles have been refreshed to the published tarball integrity.

@socket-security

socket-security Bot commented May 20, 2026

Copy link
Copy Markdown

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Diff Package Supply Chain
Security
Vulnerability Quality Maintenance License
Updated@​inertiajs/​svelte@​2.0.17 ⏵ 3.1.185 +410073 +498 +2100
Updated@​inertiajs/​react@​2.2.15 ⏵ 3.1.11001007498 +1100
Updated@​inertiajs/​vue3@​2.0.17 ⏵ 3.1.110010074 +398 +2100
Updatedinertia-sails@​1.0.1 ⏵ 1.4.077 -2310010091 -9100
Updatedaxios@​1.13.2 ⏵ 1.16.185 -11100 +5010094100

View full report

@DominusKelvin

Copy link
Copy Markdown
Member Author

Axios / Rsbuild decision

Upstream confirmed that resolve.alias: { axios: false } is the intended Rsbuild-side workaround when an app uses Inertia v3's default XHR client and does not opt into axiosAdapter().

For this migration, we are intentionally not hiding that workaround inside inertia-sails and not asking Shipwright to special-case Inertia. Having inertia-sails mutate sails.config.shipwright would be surprising, and putting the alias in every template still leaves app authors with a build-system workaround to understand.

So PR #199 keeps axios as an explicit temporary compatibility dependency in the templates. This is boring and reversible:

  • no hidden Shipwright config mutation
  • no template-level alias that breaks direct axios imports
  • apps that choose axiosAdapter() continue to work
  • once Inertia can avoid exposing the optional Axios adapter import from the main client bundle, we can remove the dependency cleanly

We should revisit this before/after the next Inertia major or if the upstream docs settle on a stronger recommendation for Rsbuild/Rspack users.

@DominusKelvin

Copy link
Copy Markdown
Member Author

Final AfricanEngineer smoke

The local inertia-sails@1.4.0 tarball has been re-packed and tested in /Users/koo/Gringotts/687/africanengineer.com on feat/test-inertia-v3-tarball.

Smoke setup:

  • @inertiajs/vue3@^3.1.1 (3.1.1 installed in this checkout)
  • inertia-sails@1.4.0 from file:../boring-stack/packages/inertia-sails/inertia-sails-1.4.0.tgz
  • axios@^1.16.1 kept explicitly for the Rsbuild/Rspack optional Axios adapter resolution issue
  • views/app.ejs updated to the Inertia v3 JSON page script boot payload
  • sails-hook-shipwright@1.3.0
  • @rsbuild/plugin-vue@1.2.8

Verification:

  • npm run lint passes
  • npm test passes
    • unit: 4/4
    • functional: 12/12
    • e2e/browser: 6/6

This confirms the v3 adapter/template changes work in a real app with full request-level and browser-level coverage.

@DominusKelvin DominusKelvin marked this pull request as ready for review May 26, 2026 20:23
@DominusKelvin DominusKelvin merged commit 2e6b1ee into main May 26, 2026
6 checks passed
@DominusKelvin DominusKelvin deleted the feat/192-support-stable-inertia-js-v3-in-inertia-sails-and-templates branch May 26, 2026 22:44
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Support stable Inertia.js v3 in inertia-sails and templates

1 participant